Release 10.1A: OpenEdge Application Server:
Developing WebSpeed Applications

Customizing field object control handlers

Field object control handlers implement the conversion between HTML and the field object for each form element and custom tag that is mapped to your Web object. This mapping is defined by the combination of your HTML Web page and the tagmap.dat file that you use for your application.

The following shows the default tagmap.dat file:

tagmap.dat 
#Default data mappable fields
#
#  Do not move the first line below from its position.  The first line is
#  the default field type for fields missing TYPE=.

input,,text,fill-in,web/support/webinput.p
input,,checkbox,toggle-box,web/support/webtog.p
input,,hidden,fill-in,web/support/webinput.p
input,,password,fill-in,web/support/webinput.p
input,,radio,radio-set,web/support/webradio.p
select,/select,,selection-list,web/support/weblist.p
textarea,/textarea,,editor,web/support/webedit.p


#Custom Tag that can be used to support HTML Tables and 3rd Party controls
!--WSTAG,,,fill-in,web/support/tagrun.p

#Custom Tag that can be used to notify an application to output messages
#messages that have queued up using the queue-message function
!--WSMSG,,,fill-in,web/support/webmsg.p

The tagmap.dat file contains the HTML field definitions that specify the types of HTML form elements and custom tags used by all the Web objects in an application. WebSpeed provides a default tagmap.dat file that supports the common HTML form elements. You can add to or modify these field definitions as required. The default definitions include the HTML form elements that you can specify with the <INPUT>,<SELECT>, and <TEXTAREA> tags.

Each HTML field definition takes up a line in tagmap.dat that conforms to the following syntax:

Syntax 
tag-name , [ closing-tag ] , [ typ-attribute ] , 
    field-object-type , [ utility-pathname ]

tag-name

The name that identifies the HTML tag. In an HTML form this is input, select, or textarea. For a custom tag, this is generally a name in the form of an HTML comment, such as !--MyTag. Using comments to define custom tags minimizes the chance of conflict with future versions of HTML. Note also that custom tags, unlike form elements, can appear anywhere in the HTML file.

closing-tag

The closing tag name for HTML tags that require them, such as /textarea.

type-attribute

The TYPE attribute for <INPUT> tags and any custom tags or future HTML tags that require a TYPE attribute such as text or hidden.

field-object-type

The type of SpeedScript field object to which this HTML or custom tag type is mapped. The supported SpeedScript field objects are EDITOR, FILL-IN, RADIO-SET, TOGGLE-BOX, and SELECTION-LIST. By default, these correspond to the HTML form elements to which they most closely resemble in both form and function. SpeedScript supports each field object with a unique set of capabilities provided by SpeedScript attributes and methods. For more information on these capabilities, see the entry for each field object (referred to online as a widget) in the OpenEdge Development: Progress 4GL Reference .

utility-pathname

The pathname of a tagmap utility procedure file that contains the default web.input and web.output control handler procedures for this HTML or custom tag type. For the default field definitions, this path is relative to the PROPATH settings. When you customize a field object control handler, you are replacing the control handler functionality provided by the corresponding tagmap utility. If you do not specify a tagmap utility procedure, you must override web.input and web.output in the AppBuilder to do equivalent work.

Note: Any line in tagmap.dat that begins with a pound sign (#) is a comment.

The Web page for the example ncust-wo.w. illustrates how the field definitions correspond to the form elements and custom tags in an HTML file, as shown:

ncust-wo.htm 
<HTML>

<BODY>

<FORM ACTION="ncust-wo.w" METHOD="post">

<CENTER>

<P><B>Enter portion of a<BR>customer last name:</B><BR>

<INPUT TYPE=text NAME="cust-prompt" SIZE=16 >

<INPUT TYPE=submit NAME="CustSearch" VALUE="Search">    </P>

</CENTER>

<P>Please enter some starting portion of a customer name 

even if only a single letter.</P>

<SELECT Name="matching-cust-names" Size=10> </SELECT>

<INPUT TYPE=submit NAME="CustDetail" VALUE="Show Detail" >   

<P>
Name:    <INPUT TYPE=text NAME="Name" SIZE=25 > <BR>
Phone: <INPUT TYPE=text NAME="Phone" SIZE=25 > <BR>
Comments: <TEXTAREA NAME="Comments" ROWS=6 COLS=60 ></TEXTAREA> <BR>
<BR>
Country:<BR>
USA <INPUT TYPE=radio NAME=Country VALUE=1><BR> 
Other <INPUT TYPE=radio NAME=Country VALUE=2> <BR><BR>
Has Orders: <INPUT TYPE=checkbox NAME="HasOrders">
</P>

<INPUT TYPE=submit NAME="CustUpdate" VALUE="Update" >   

</FORM>

</BODY>

</HTML>

When the TagExtract utility generates the offset file for this Web page using the default tagmap.dat file, it generates this offset file:

ncust-wo.off 
/* HTML offsets */
htm-file= /working-directory-path/ncust-wo.htm
version= AB_v19r1

field[1]= "cust-prompt,INPUT,text,fill-in,11,1,11,45"
field[2]= "matching-cust-names,SELECT,,selection-list,21,1,21,53"
field[3]= "Name,INPUT,text,fill-in,26,10,26,47"
field[4]= "Phone,INPUT,text,fill-in,27,8,27,46"
field[5]= "Comments,TEXTAREA,,editor,28,11,28,63"
field[6]= "Country,INPUT,radio,radio-set,31,5,31,43"
field[7]= "Country,INPUT,radio,radio-set,32,7,32,45"
field[8]= "HasOrders,INPUT,checkbox,toggle-box,33,13,33,50"

Note: You can interrupt offset generation at any point in an HTML file by inserting <!--TagExtractSuspend--> at that point. You can then resume offset generation by inserting <!--TagExtractResume--> at a following point in the file.

The offset file records each mappable tag (field) in order of its occurrence in the HTML file. For each tag (field[6]), it records the NAME attribute value (Country), tag TYPE (INPUT), HTML visualization (radio), the corresponding SpeedScript field object type (radio-set) from tagmap.dat, and four integers that record the starting line, starting character, ending line, and ending character of the tag specification in the HTML file (31,5,31,43). The only relevant information missing from this file is the location of the tagmap utility procedures. WebSpeed continues to get this information both during development and at run time from the tagmap.dat file (web/support/webradio.p).

Note: TagExtract understands UNIX pathnames in tagmap.dat (web/support/webradio.p) as well as MS-DOS pathnames (web\support\webradio.p). However, when you move your application to UNIX, you can only use UNIX pathnames. Therefore, tagmap.dat uses UNIX pathnames by default.

For many applications, the default tagmap utilities work well with the default tags. However, you can replace the default web.input or web.output control handler for any tag using the control handler templates shown in the following:

web.input 
/*------------------------------------------------------------------------
  Purpose:     Assigns form field data value to frame screen value.
  Parameters:  p-field-value
  Notes:       
------------------------------------------------------------------------*/
  DEFINE INPUT PARAMETER p-field-value AS CHARACTER NO-UNDO.
  
  DO WITH FRAME {&FRAME-NAME}:
  
  END.
  
END PROCEDURE.

web.output 
/*------------------------------------------------------------------------
  Purpose:     Output the value of the field to the WEB stream
               in place of the HTML field definition.
  Parameters:  p-field-defn
  Notes:       
------------------------------------------------------------------------*/
  DEFINE INPUT PARAMETER p-field-defn AS CHARACTER NO-UNDO.
  
  DO WITH FRAME {&FRAME-NAME}:

  END.
  
END PROCEDURE.

Each template passes the same parameter for every tag. For web.input, this is the current input value associated with the tag, expressed as a character string. This value is actually the output of the get-field() API function for the HTML field name.

For web.output the parameter is the full HTML tag specification for the field from the source HTML file. If you want the output value, you must access the SpeedScript SCREEN-VALUE attribute of the field object associated with the tag. You can reference the attribute using the full name of the field object. The field object name always has the same name as the NAME attribute for the associated tag (replacing embedded spaces with underscores ( _ ) and removing any illegal SpeedScript characters). Thus, for the Name field in ncust-wo.htm you can access the form buffer value using Name:SCREEN-VALUE.

If the SpeedScript field object is a radio set, web.output executes once for each radio item. A second parameter (the item number) is also passed into the control handler.

Placing your code inside the default DO block ensures that the object is properly referenced in its SpeedScript frame. Note also that, if the field object maps to a database field, the object name can be prefixed by the database and table names separated by periods (for example, sports2000.Customer.Name), depending on your AppBuilder settings.

Finally, when creating custom tags, you can create your own tagmap utility procedures, such as webinput.p. However, it is very common to rely on the web.input and web.output control handlers in the Web object itself, instead of defining a separate utility procedure for the tag. This works when the custom tag maps to a standard SpeedScript field object like fill-in.

Copyright © 2005 Progress Software Corporation
 www.progress.com
Voice: (781) 280-4000
Fax: (781) 280-4095